USB API reference

This topic describes the USB API, the file system that that the API creates on the USB memory drive, the data structures the API uses, usage examples, descriptions of the USB API functions, and some USB API error codes.

USB API overview

You can use the USB API to write applications that can interact with the HSM via the card USB port:

This functionality can include:

• wrapping of PKCS objects and storing them on a USB flash memory drive

• Performing backup of SMFS stored key (non-PKCS keys)

The USB API works with your custom FM to enable the desired functionality.

USB file system

The file system that the API creates on the USB memory drive is structured as follows:

The memory block size is determined automatically and has the most common value of 512 octets.

• <DataLen> and <LabelLen>: These fields have a uint32 data type and they are stored in the USB memory as Big Endian values.

• <FSLabel>: a 0-terminated string with a maximum length of 32 bytes.

Data structures

The following two data structures are used in the FM USB API:

typedef struct _capacity {
        uint32_t max_lba_msb;    //used for 'Read Capacity 16'. Contains MSB of max block number.
        uint32_t max_lba;        //max number of logical block on the device for 'Read Capacity 10' or LSB of max number of logical block for 'Read Capacity 16'.
        uint32_t block_size;
        uint32_t device_size;    //Contains device size in Gb. 32 bits are capable to hold the capacity of 4 Gb.
} capacity_t;



typedef struct _dev_properties {
        uint16_t vendorId;
        uint16_t productId;
        uint8_t endpoint_in;
        uint8_t endpoint_out;
} dev_properties_t;

Example USB API usage

Currently, one application of the USB API is supported. The following scenario assumes that cryptographic object A exists on the HSM token.

To wrap object A from the HSM token to a USB memory drive

1. Create wrapping key B using BPE.

2. Wrap object A with wrapping key B.

3. Copy wrapped key to USB memory drive using the FM USB API calls.

4. (Optional) Destroy wrapping key B and object A on the HSM token.

To restore the source object A to the token

1. Read wrapped object A from the USB memory drive.

2. Create a new wrapping key B with BPE (or use existing key if it was never deleted).

3. Unwrap wrapped object A on the HSM token.

Function descriptions

Functions included in this reference are:

• USBFS_Close

• USBFS_Destroy

• USBFS_Finalize

• USBFS_GetInfo

• USBFS_Init

• USBFS_New

• USBFS_Open

• USBFS_ReadData

• USBFS_WriteData

This chapter also contains a list of vendor-defined error codes that can be produced by the USB API:

• USB API vendor-defined error codes

USBFS_Close

Writes the header from the HSM memory back to the USB file system.

Synopsis

int USBFS_Close(
    void *handlev, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t *header
);

Input parameters

Input requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API vendor-defined error codes.

USBFS_Destroy

Destroys the existing USB file system, including label and size.

Synopsis

int USBFS_Destroy(
    void *handle, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t **header
);

Input parameters

Input requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API vendor-defined error codes.

USBFS_Finalize

Finalizes the USB API sequence.

This is the last function required in any sequence of USB-related calls. It frees context, device handler, attaches the kernel driver if required, and frees any memory that was allocated for the FS header.

Synopsis

int USBFS_Finalize(
    void *ctx, 
    void *handlev, 
    int *kernelDriverAttachedFlag, 
    uint8_t **header
);

Input parameters

Input requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API vendor-defined error codes.

USBFS_GetInfo

Returns the USB file system label and the length of the stored data in bytes.

Synopsis

int USBFS_GetInfo(
    void *handle, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint32_t *dataLen, 
    uint8_t *label, 
    uint8_t *header
);

Input parameters

Input requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API vendor-defined error codes.

USBFS_Init

Initializes the USB sub-system and returns the USB handle.

This is the first function required in any sequence of USB-related calls. It returns context, USB handler, properties and capacity structures, and the "Kernel Driver attached" flag (which indicates whether the kernel driver should be attached at the end of the execution).

Synopsis

int USBFS_Init(
    void *ctxv, 
    void **handlev, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    int *kernelDriverAttachedFlag
);

Input parameters

Input requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API vendor-defined error codes.

USBFS_New

Creates a new, empty file system.

This function allocates space for the file system header, which contains only label length and label fields.

Synopsis

int USBFS_New(
    void *handle, 
    char * label, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t **header
);

Input parameters

Input requirements

The USBFS library has been initialized with USBFS_Init(), and there is no current existing file system.

Return value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API vendor-defined error codes.

If a file system already exists, CKR_USB_INITIALIZED is returned. Use USB_Destroy() first to erase the current file system.

USBFS_Open

Reads the header into the HSM memory.

Synopsis

int USBFS_Open(
    void *handle, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t **header
);

Input parameters

Input requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API vendor-defined error codes.

USBFS_ReadData

Reads specified number of bytes from the USB file system to the HSM memory.

Synopsis

int USBFS_ReadData(
    void *handle, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t *data, 
    uint32_t *dataLen, 
    uint8_t *header
);

Input parameters

Input requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API vendor-defined error codes.

USBFS_WriteData

Writes the specified number of bytes (dataLen) to the USB file system, starting from block 1. This will overwrite the existing contents.

Synopsis

int USBFS_WriteData(
    void *handle, 
    dev_properties_t *dp, 
    capacity_t *cap, 
    uint8_t *data, 
    uint32_t dataLen, 
    uint8_t *header
);

Input parameters

Input requirements

Refer to the FM sample usbdemo for the call sequence requirements.

Return value

The function returns CKR_USB_OK if successful, or one of the error codes in USB API vendor-defined error codes.

USB API Vendor-Defined Error Codes

The table below lists the error codes that may be returned from USB API calls.